fix(nodes-base): fix and harmonize all primaryDocumentation links #4191

mieky · 2022-09-26T11:14:30Z

This is a housekeeping 🏠 🔨 PR to bring all the primaryDocumentation links in nodes-base up to date and help @StarfallProjects keep them tidy.

With the help of a few custom scripts, I was able to locate and fix a couple of 404 links, malformed JSONs, and unnecessary redirects. The bulk of this change is to crawl all primaryDocumentation links in node descriptor files, and for those that would be redirected (HTTP 301), replace the JSON with their actual target.

Finally, ran npx prettier --write nodes/**/*.node.json to pretty-print the files.

With this change, all node URLs should take us directly to their correct documentation pages, and we can further clean up some of the manual redirects in the docs.

linear · 2022-09-26T11:14:32Z

N8N-4715

StarfallProjects

Looks good to me.

ivov

URL is case-insensitive so the link will work, but should we be allowing for this casing divergence? n8n-nodes-base.activecampaigntrigger vs. n8n-nodes-base.activeCampaignTrigger The canonical name is camelCased after the prefix. No immediate risk that I can think of, but I would avoid this divergence if we can help it.
With the help of a few custom scripts, I was able to locate and fix a couple of 404 links, malformed JSONs, and unnecessary redirects. Can you add a task to automate this in future? Via CI or an n8n workflow.
npx prettier --write nodes/**/*.node.json Can you update the format command to format these files as well?

StarfallProjects · 2022-09-26T13:21:52Z

URL is case-insensitive so the link will work, but should we be allowing for this casing divergence? n8n-nodes-base.activecampaigntrigger vs. n8n-nodes-base.activeCampaignTrigger The canonical name is camelCased after the prefix. No immediate risk that I can think of, but I would avoid this divergence if we can help it.

Our hosting automatically lowercases URLs (this is the background to making the links lowercase)

ivov · 2022-09-26T13:36:44Z

URL is case-insensitive so the link will work, but should we be allowing for this casing divergence? n8n-nodes-base.activecampaigntrigger vs. n8n-nodes-base.activeCampaignTrigger The canonical name is camelCased after the prefix. No immediate risk that I can think of, but I would avoid this divergence if we can help it.

Our hosting automatically lowercases URLs (this is the background to making the links lowercase)

That's unfortunate. Please disregard.

krynble

Nice

Perhaps we can also change

n8n/packages/editor-ui/src/components/NodeSettingsTabs.vue

Line 49 in 6ac442a

    
           				return 'https://docs.n8n.io/nodes/' + (nodeType.documentationUrl || nodeType.name) + '?utm_source=n8n_app&utm_medium=node_settings_modal-credential_link&utm_campaign=' + nodeType.name;

so it also reflects the new URLs? Without this change n8n continues sending users to the wrong URL, requiring the 301 to be there forever.

mieky · 2022-09-28T09:06:26Z

Perhaps we can also change (link) so it also reflects the new URLs? Without this change n8n continues sending users to the wrong URL, requiring the 301 to be there forever.

Ahh, great catch! Thanks for pointing this out, I'll check this one.

…ptor json

mieky · 2022-09-28T11:46:38Z

packages/cli/src/LoadNodesAndCredentials.ts

+		const { categories, subcategories, resources: allResources, alias } = require(`${filePath}on`); // .js to .json
+
+		const resources = pick(allResources, ['primaryDocumentation', 'credentialDocumentation']);
+
 		// eslint-disable-next-line @typescript-eslint/no-unsafe-return
 		return {
 			...(categories && { categories }),
 			...(subcategories && { subcategories }),
+			...(resources && { resources }),
 			...(alias && { alias }),
 		};
 	}


My thinking is that in the long run the only maintainable way is to get the doc links directly from the node descriptor (codex). I now exposed resources.primaryDocumentation and resources.credentialDescription so that the UI can access and use those, instead of having to generate the URLs dynamically from parts.

mieky · 2022-09-28T11:47:32Z

packages/editor-ui/src/components/CredentialEdit/CredentialConfig.vue

 				'' : // Don't show documentation link for community nodes if the URL is not an absolute path
-				`https://docs.n8n.io/credentials/${type.documentationUrl}/?utm_source=n8n_app&utm_medium=left_nav_menu&utm_campaign=create_new_credentials_modal`;
+				`${BUILTIN_CREDENTIALS_DOCS_URL}${type.documentationUrl}/?utm_source=n8n_app&utm_medium=left_nav_menu&utm_campaign=create_new_credentials_modal`;


Parametrized the credential link URL prefix.

mieky · 2022-09-28T12:03:11Z

packages/editor-ui/src/components/NodeSettingsTabs.vue

+			// Built-in node documentation available via its codex entry
+			const primaryDocUrl = nodeType.codex?.resources?.primaryDocumentation?.[0]?.url;
+			if (primaryDocUrl) {
+				return primaryDocUrl + utmTags;
+			}


All our built-in nodes (with the exception of the StickyNote, I think) have a primary documentation link defined in their descriptor, so let's use that directly where it applies.

mieky · 2022-09-28T12:09:06Z

packages/workflow/src/Interfaces.ts

+	resources?: {
+		credentialDocumentation?: DocumentationLink[];
+		primaryDocumentation?: DocumentationLink[];
+	};


Exposing documentation links as part of a node's CodexData.

mieky · 2022-09-28T12:09:48Z

packages/nodes-base/package.json

@@ -18,7 +18,7 @@
    "dev": "npm run watch",
    "build": "tsc && gulp build:icons && gulp build:translations",
    "build:translations": "gulp build:translations",
-    "format": "cd ../.. && node_modules/prettier/bin-prettier.js --write \"packages/nodes-base/**/*.ts\"",
+    "format": "cd ../.. && node_modules/prettier/bin-prettier.js --write \"packages/nodes-base/**/*.{ts,json}\"",


Formatting also JSON files now.

mieky · 2022-09-28T12:15:26Z

@krynble @ivov Thanks for the great input! I refactored how the documentation links are formed, and so far all the ones I clicked would seem to open the correct URL directly. It's possible there's a case I might have missed, but the logic overall seems quite solid. I also updated some more old links that obviously would either get straight up redirected or were just broken.

Also created a N8N-4791 for including the helper scripts in the repo, to make it easier to deal with these links in the future. Pointed my most notable changes as line comments.

krynble

LGTM!

janober · 2022-09-30T16:04:02Z

Got released with [email protected]

…n-io#4191) * fix(nodes-base): fix and harmonize all primaryDocumentation links * feat(workflow, cli): expose documentation links to UI via node codex * fix(editor-ui): link to correct node and credential documentation URLs * config(nodes-base): update 'format' script to also format node descriptor json * chore: fix outdated links to node reference documentation

fix(nodes-base): fix and harmonize all primaryDocumentation links

456e374

mieky requested a review from krynble September 26, 2022 11:14

mieky requested a review from StarfallProjects September 26, 2022 11:14

mieky marked this pull request as ready for review September 26, 2022 11:23

n8n-assistant bot added n8n team Authored by the n8n team node/improvement New feature or request labels Sep 26, 2022

StarfallProjects previously approved these changes Sep 26, 2022

View reviewed changes

ivov reviewed Sep 26, 2022

View reviewed changes

krynble previously approved these changes Sep 27, 2022

View reviewed changes

mieky added 4 commits September 28, 2022 13:45

feat(workflow, cli): expose documentation links to UI via node codex

49c0068

fix(editor-ui): link to correct node and credential documentation URLs

860ff46

config(nodes-base): update 'format' script to also format node descri…

d8144cb

…ptor json

chore: fix outdated links to node reference documentation

63b8b32

mieky dismissed stale reviews from krynble and StarfallProjects via 63b8b32 September 28, 2022 11:05

fix(cli): add missing dependency for lodash.pick

a6197c4

mieky commented Sep 28, 2022

View reviewed changes

mieky requested a review from krynble September 28, 2022 12:15

krynble approved these changes Sep 29, 2022

View reviewed changes

mieky merged commit 6e8e4f5 into master Sep 29, 2022

mieky deleted the n8n-4715-update-node-doc-links branch September 29, 2022 10:33

n8n-assistant bot added the Upcoming Release Will be part of the upcoming release label Sep 29, 2022

janober removed the Upcoming Release Will be part of the upcoming release label Sep 30, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(nodes-base): fix and harmonize all primaryDocumentation links #4191

fix(nodes-base): fix and harmonize all primaryDocumentation links #4191

mieky commented Sep 26, 2022 •

edited

Loading

linear bot commented Sep 26, 2022

StarfallProjects left a comment

ivov left a comment

StarfallProjects commented Sep 26, 2022

ivov commented Sep 26, 2022

krynble left a comment

mieky commented Sep 28, 2022

mieky Sep 28, 2022 •

edited

Loading

mieky Sep 28, 2022

mieky Sep 28, 2022

mieky Sep 28, 2022

mieky Sep 28, 2022

mieky commented Sep 28, 2022

krynble left a comment

janober commented Sep 30, 2022

fix(nodes-base): fix and harmonize all primaryDocumentation links #4191

fix(nodes-base): fix and harmonize all primaryDocumentation links #4191

Conversation

mieky commented Sep 26, 2022 • edited Loading

linear bot commented Sep 26, 2022

StarfallProjects left a comment

Choose a reason for hiding this comment

ivov left a comment

Choose a reason for hiding this comment

StarfallProjects commented Sep 26, 2022

ivov commented Sep 26, 2022

krynble left a comment

Choose a reason for hiding this comment

mieky commented Sep 28, 2022

mieky Sep 28, 2022 • edited Loading

Choose a reason for hiding this comment

mieky Sep 28, 2022

Choose a reason for hiding this comment

mieky Sep 28, 2022

Choose a reason for hiding this comment

mieky Sep 28, 2022

Choose a reason for hiding this comment

mieky Sep 28, 2022

Choose a reason for hiding this comment

mieky commented Sep 28, 2022

krynble left a comment

Choose a reason for hiding this comment

janober commented Sep 30, 2022

mieky commented Sep 26, 2022 •

edited

Loading

mieky Sep 28, 2022 •

edited

Loading